Configure a customer's agent billing policy
Create or replace one billing scope — the default policy, or one agent’s own when agent is passed. Whole-row replacement. Sending plan_id attaches the customer to that plan: the plan supplies the mode, overage stance, rate card, windows and markups, and when the plan carries a minted invoice container the customer’s subscription gains its overage line (a minimal monthly subscription is opened when they have none). Choosing wallet mode opens the customer’s wallet if they have none; credits mode opens their pot. Both open EMPTY — the policy makes the customer billable, it grants them nothing.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Query Parameters
Agent scope identifier. Null on scoped results denotes the customer's shared pool.
1 - 128"support"
Body
Upsert billing policy payload
Billing mode.
- wallet: Charges a monetary wallet.
- credits: Consumes a credit balance.
- windows: Meters weighted units against rolling allowances.
wallet, credits, windows "wallet"
Whether spending is disabled for this billing scope.
false
Customer wallet identifier. Omit on wallet policy writes to provision or reuse the customer's wallet.
1"wal_example"
Public credit product identifier whose balance this policy consumes.
1"prd_credits"
Percentage added to resolved cost. Null on writes means no override; an attached plan may supply the value.
40^\d+(\.\d+)?$"20"
Behavior when credits or an allowance are exhausted. Policy values may inherit the attached plan.
- refuse: Rejects the call that crosses the boundary without deducting usage.
- metered: Prices the whole call as monetary overage, using the overage card or USD provider cost plus markup.
refuse, metered "metered"
Percentage added to provider cost for overage. Mutually exclusive with overage_rate_card_id.
40^\d+(\.\d+)?$"10"
Currency rate card used to price overage directly. Null means provider cost plus the resolved overage markup.
1"airc_overage"
Wallet charged for overage. Null bills overage in arrears.
1"wal_example"
Minimum available balance a spend check requires, in the policy's denomination.
40^\d+(\.\d+)?$"0"
Settlement interval in minutes. Null means no interval override. Mutually exclusive with settlement_schedule.
60 <= x <= 4464060
Calendar settlement schedule. Null clears the override; mutually exclusive with settlement_interval_minutes.
- calendar_month: Settles at the end of each UTC calendar month.
calendar_month "calendar_month"
Inline credit pricing. Mutually exclusive with rate_card_id. Omitted rates may be supplied by a plan or product default.
Window definitions and optional inline unit rates. An attached plan may supply omitted definitions; rate_card_id may supply unit rates.
Rate card reference. On policy writes, omission preserves the current reference and null detaches it; on plan replacement omission clears it.
1"airc_example"
Billing plan reference. On policy writes, omission preserves the current plan and null detaches it.
1"aiplan_example"
Response
Unique Hyperline identifier for this resource.
"d18603dd-7285-4bf5-a45e-88d7de8f37c9"
Hyperline customer identifier.
"cus_example"
Agent scope identifier. Null is the customer's shared pool.
"support"
Whether this is the default plan or shared customer scope.
false
Billing mode.
- wallet: Charges a monetary wallet.
- credits: Consumes a credit balance.
- windows: Meters weighted units against rolling allowances.
wallet, credits, windows "wallet"
Customer wallet identifier. Omit on wallet policy writes to provision or reuse the customer's wallet.
"wal_example"
Public credit product identifier whose balance this policy consumes.
"prd_credits"
Percentage added to resolved cost. Null on writes means no override; an attached plan may supply the value.
^-?\d+(\.\d+)?(e[+-]?\d+)?$/i"20"
Behavior when credits or an allowance are exhausted. Policy values may inherit the attached plan.
- refuse: Rejects the call that crosses the boundary without deducting usage.
- metered: Prices the whole call as monetary overage, using the overage card or USD provider cost plus markup.
refuse, metered "metered"
Percentage added to provider cost for overage. Mutually exclusive with overage_rate_card_id.
^-?\d+(\.\d+)?(e[+-]?\d+)?$/i"10"
Currency rate card used to price overage directly. Null means provider cost plus the resolved overage markup.
"airc_overage"
Source of the effective overage rate card. Null when no card is configured.
- policy: Selected directly on the customer policy.
- plan: Inherited from the attached plan.
policy, plan "plan"
Wallet charged for overage. Null bills overage in arrears.
"wal_example"
Minimum available balance a spend check requires, in the policy's denomination.
^-?\d+(\.\d+)?(e[+-]?\d+)?$/i"0"
Inline credit pricing. Mutually exclusive with rate_card_id. Omitted rates may be supplied by a plan or product default.
Window definitions and optional inline unit rates. An attached plan may supply omitted definitions; rate_card_id may supply unit rates.
Rate card reference. On policy writes, omission preserves the current reference and null detaches it; on plan replacement omission clears it.
"airc_example"
Source of the effective rate card. Null when no card is configured.
- policy: Selected directly on the customer policy.
- plan: Inherited from the attached plan.
policy, plan "policy"
Attached plan summary, or null.
Settlement interval in minutes. Null means no interval override. Mutually exclusive with settlement_schedule.
60
Calendar settlement schedule. Null clears the override; mutually exclusive with settlement_interval_minutes.
- calendar_month: Settles at the end of each UTC calendar month.
calendar_month "calendar_month"
Summary of the effective pricing after applying rate-card inheritance. Null when no card resolves.
Whether spending is disabled for this billing scope.
false
Creation time as a UTC ISO 8601 timestamp.
"2026-09-01T00:00:00Z"
Last update time as a UTC ISO 8601 timestamp.
"2026-09-02T12:00:00Z"

